<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
 <head>
  <meta http-equiv="content-type" content="text/html; charset=UTF-8">
  <title>The SessionHandler class</title>

 </head>
 <body><div class="manualnavbar" style="text-align: center;">
 <div class="prev" style="text-align: left; float: left;"><a href="function.session-write-close.html">session_write_close</a></div>
 <div class="next" style="text-align: right; float: right;"><a href="sessionhandler.close.html">SessionHandler::close</a></div>
 <div class="up"><a href="book.session.html">Sessions</a></div>
 <div class="home"><a href="index.html">PHP Manual</a></div>
</div><hr /><div id="class.sessionhandler" class="reference">

 <h1 class="title">The SessionHandler class</h1>
 

 <div class="partintro"><p class="verinfo">(PHP 5 &gt;= 5.4.0)</p>


  <div class="section" id="sessionhandler.intro">
   <h2 class="title">简介</h2>
   <p class="para">
    <strong class="classname">SessionHandler</strong> a special class that can be used to expose
    the current internal PHP session save handler by inheritance.  There are six methods which
    wrap the six internal session save handler callbacks (<em><code class="parameter">open</code></em>, <em><code class="parameter">close</code></em>,
    <em><code class="parameter">read</code></em>, <em><code class="parameter">write</code></em>, <em><code class="parameter">destroy</code></em> and <em><code class="parameter">gc</code></em>).
    By default, this class will wrap whatever internal save handler is set as as defined by the
    <a href="session.configuration.html#ini.session.save-handler" class="link">session.save_handler</a> configuration directive which is usually
    <em><code class="parameter">files</code></em> by default.
    Other internal session save handlers are provided by PHP extensions such as SQLite (as <em><code class="parameter">sqlite</code></em>),
    Memcache (as <em><code class="parameter">memcache</code></em>), and Memcached (as <em><code class="parameter">memcached</code></em>).
   </p>
   <p class="para">
    When a plain instance of <strong class="classname">SessionHandler</strong> is set as the save handler using
    <span class="function"><a href="function.session-set-save-handler.html" class="function">session_set_save_handler()</a></span> it will wrap the current save handlers.
    A class extending from <strong class="classname">SessionHandler</strong> allows you to override
    the methods or intercept or filter them by calls the parent class methods which ultimately wrap
    the interal PHP session handlers.
   </p>
   <p class="para">
    This allows you, for example, to intercept the <em><code class="parameter">read</code></em> and <em><code class="parameter">write</code></em>
    methods to encrypt/decrypt the session data and then pass the result to and from the parent class.
    Alternatively one might chose to entirely override a method like the garbage collection callback
    <em><code class="parameter">gc</code></em>.
   </p>
   <p class="para">
    Because the <strong class="classname">SessionHandler</strong> wraps the current internal save handler
    methods, the above example of encryption can be applied to any internal save handler without
    having to know the internals of the handlers.
   </p>
   <p class="para">
    To use this class, first set the save handler you wish to expose using
    <a href="session.configuration.html#ini.session.save-handler" class="link">session.save_handler</a> and then pass an instance of
    <strong class="classname">SessionHandler</strong> or one extending it to <span class="function"><a href="function.session-set-save-handler.html" class="function">session_set_save_handler()</a></span>.
   </p>
   <p class="para">
    Please note the callback methods of this class are designed to be called internally by
    PHP and are not meant to be called from user-space code.  The return values are equally processed internally
    by PHP.  For more information on the session workflow, please refer <span class="function"><a href="function.session-set-save-handler.html" class="function">session_set_save_handler()</a></span>.
   </p>
  </div>


  <div class="section" id="sessionhandler.synopsis">
   <h2 class="title">类摘要</h2>


   <div class="classsynopsis">
    <div class="ooclass"></div>


    <div class="classsynopsisinfo">
     <span class="ooclass">
      <strong class="classname">SessionHandler</strong>
     </span>

     <span class="oointerface">implements 
      <span class="interfacename"><a href="class.sessionhandlerinterface.html" class="interfacename">SessionHandlerInterface</a></span>
     </span>
     {</div>


    <div class="classsynopsisinfo classsynopsisinfo_comment">/* 方法 */</div>
    <div class="methodsynopsis dc-description">
   <span class="modifier">public</span> <span class="type">bool</span><span class="methodname"><a href="sessionhandler.close.html" class="methodname">close</a></span>
    ( <span class="methodparam">void</span>
   )</div>
<div class="methodsynopsis dc-description">
  <span class="modifier">public</span> <span class="type">bool</span><span class="methodname"><a href="sessionhandler.destroy.html" class="methodname">destroy</a></span>
   ( <span class="methodparam"><span class="type">string</span> <code class="parameter">$session_id</code></span>
   )</div>
<div class="methodsynopsis dc-description">
   <span class="modifier">public</span> <span class="type">bool</span><span class="methodname"><a href="sessionhandler.gc.html" class="methodname">gc</a></span>
    ( <span class="methodparam"><span class="type">int</span> <code class="parameter">$maxlifetime</code></span>
   )</div>
<div class="methodsynopsis dc-description">
   <span class="modifier">public</span> <span class="type">bool</span><span class="methodname"><a href="sessionhandler.open.html" class="methodname">open</a></span>
    ( <span class="methodparam"><span class="type">string</span> <code class="parameter">$save_path</code></span>
   , <span class="methodparam"><span class="type">string</span> <code class="parameter">$session_id</code></span>
   )</div>
<div class="methodsynopsis dc-description">
   <span class="modifier">public</span> <span class="type">string</span><span class="methodname"><a href="sessionhandler.read.html" class="methodname">read</a></span>
    ( <span class="methodparam"><span class="type">string</span> <code class="parameter">$session_id</code></span>
   )</div>
<div class="methodsynopsis dc-description">
   <span class="modifier">public</span> <span class="type">bool</span><span class="methodname"><a href="sessionhandler.write.html" class="methodname">write</a></span>
    ( <span class="methodparam"><span class="type">string</span> <code class="parameter">$session_id</code></span>
   , <span class="methodparam"><span class="type">string</span> <code class="parameter">$session_data</code></span>
   )</div>

   }</div>


  </div>

  <div class="section" id="session.notes">
   <div class="warning"><strong class="warning">Warning</strong>
    <p class="para">
     This class is designed to expose the current internal PHP session save handler, if you you want to
     write your own custom save handlers, please implement the <a href="class.sessionhandlerinterface.html" class="classname">SessionHandlerInterface</a>
     interface instead of extending from <strong class="classname">SessionHandler</strong>.
    </p>
   </div>
  </div>

  <div class="section" id="sessionhandler.examples">
   <div class="example" id="example-4676">
    <p><strong>Example #1 
     Using <strong class="classname">SessionHandler</strong> to add encryption to internal PHP save handlers.
    </strong></p>
    <div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB">&lt;?php<br /></span><span style="color: #007700">class&nbsp;</span><span style="color: #0000BB">EncryptedSessionHandler&nbsp;</span><span style="color: #007700">extends&nbsp;</span><span style="color: #0000BB">SessionHandler<br /></span><span style="color: #007700">{<br />&nbsp;&nbsp;&nbsp;&nbsp;private&nbsp;</span><span style="color: #0000BB">$key</span><span style="color: #007700">;<br /><br />&nbsp;&nbsp;&nbsp;&nbsp;public&nbsp;function&nbsp;</span><span style="color: #0000BB">__construct</span><span style="color: #007700">(</span><span style="color: #0000BB">$key</span><span style="color: #007700">)<br />&nbsp;&nbsp;&nbsp;&nbsp;{<br />&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</span><span style="color: #0000BB">$this</span><span style="color: #007700">-&gt;</span><span style="color: #0000BB">key&nbsp;</span><span style="color: #007700">=&nbsp;</span><span style="color: #0000BB">$key</span><span style="color: #007700">;<br />&nbsp;&nbsp;&nbsp;&nbsp;}<br /><br />&nbsp;&nbsp;&nbsp;&nbsp;public&nbsp;function&nbsp;</span><span style="color: #0000BB">read</span><span style="color: #007700">(</span><span style="color: #0000BB">$id</span><span style="color: #007700">)<br />&nbsp;&nbsp;&nbsp;&nbsp;{<br />&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</span><span style="color: #0000BB">$data&nbsp;</span><span style="color: #007700">=&nbsp;</span><span style="color: #0000BB">parent</span><span style="color: #007700">::</span><span style="color: #0000BB">read</span><span style="color: #007700">(</span><span style="color: #0000BB">$id</span><span style="color: #007700">);<br /><br />&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;return&nbsp;</span><span style="color: #0000BB">mcrypt_decrypt</span><span style="color: #007700">(</span><span style="color: #0000BB">MCRYPT_3DES</span><span style="color: #007700">,&nbsp;</span><span style="color: #0000BB">$this</span><span style="color: #007700">-&gt;</span><span style="color: #0000BB">key</span><span style="color: #007700">,&nbsp;</span><span style="color: #0000BB">$data</span><span style="color: #007700">,&nbsp;</span><span style="color: #0000BB">MCRYPT_MODE_ECB</span><span style="color: #007700">);<br />&nbsp;&nbsp;&nbsp;&nbsp;}<br /><br />&nbsp;&nbsp;&nbsp;&nbsp;public&nbsp;function&nbsp;</span><span style="color: #0000BB">write</span><span style="color: #007700">(</span><span style="color: #0000BB">$id</span><span style="color: #007700">,&nbsp;</span><span style="color: #0000BB">$data</span><span style="color: #007700">)<br />&nbsp;&nbsp;&nbsp;&nbsp;{<br />&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</span><span style="color: #0000BB">$data&nbsp;</span><span style="color: #007700">=&nbsp;</span><span style="color: #0000BB">mcrypt_encrypt</span><span style="color: #007700">(</span><span style="color: #0000BB">MCRYPT_3DES</span><span style="color: #007700">,&nbsp;</span><span style="color: #0000BB">$this</span><span style="color: #007700">-&gt;</span><span style="color: #0000BB">key</span><span style="color: #007700">,&nbsp;</span><span style="color: #0000BB">$data</span><span style="color: #007700">,&nbsp;</span><span style="color: #0000BB">MCRYPT_MODE_ECB</span><span style="color: #007700">);<br /><br />&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;return&nbsp;</span><span style="color: #0000BB">parent</span><span style="color: #007700">::</span><span style="color: #0000BB">write</span><span style="color: #007700">(</span><span style="color: #0000BB">$id</span><span style="color: #007700">,&nbsp;</span><span style="color: #0000BB">$data</span><span style="color: #007700">);<br />&nbsp;&nbsp;&nbsp;&nbsp;}<br />}<br /><br /></span><span style="color: #FF8000">//&nbsp;we'll&nbsp;intercept&nbsp;the&nbsp;native&nbsp;'files'&nbsp;handler,&nbsp;but&nbsp;will&nbsp;equally&nbsp;work<br />//&nbsp;with&nbsp;other&nbsp;internal&nbsp;native&nbsp;handlers&nbsp;like&nbsp;'sqlite',&nbsp;'memcache'&nbsp;or&nbsp;'memcached'<br />//&nbsp;which&nbsp;are&nbsp;provided&nbsp;by&nbsp;PHP&nbsp;extensions.<br /></span><span style="color: #0000BB">ini_set</span><span style="color: #007700">(</span><span style="color: #DD0000">'session.save_handler'</span><span style="color: #007700">,&nbsp;</span><span style="color: #DD0000">'files'</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">$handler&nbsp;</span><span style="color: #007700">=&nbsp;new&nbsp;</span><span style="color: #0000BB">EncryptedSessionHandler</span><span style="color: #007700">(</span><span style="color: #DD0000">'mykey'</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">session_set_save_handler</span><span style="color: #007700">(</span><span style="color: #0000BB">$handler</span><span style="color: #007700">,&nbsp;</span><span style="color: #0000BB">true</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">session_start</span><span style="color: #007700">();<br /><br /></span><span style="color: #FF8000">//&nbsp;proceed&nbsp;to&nbsp;set&nbsp;and&nbsp;retrieve&nbsp;values&nbsp;by&nbsp;key&nbsp;from&nbsp;$_SESSION</span>
</span>
</code></div>
    </div>

   </div>
   <blockquote class="note"><p><strong class="note">Note</strong>: 
    <p class="para">
     Since this class&#039; methods are designed to be called internally by PHP as part of the normal session workflow,
     child class calls to parent methods (i.e. the actual internal native handlers) will return <strong><code>FALSE</code></strong> unless
     the session has actually been started (either automatically, or by explicit <span class="function"><a href="function.session-start.html" class="function">session_start()</a></span>.
     This is important to consider when writing unit tests where the class methods might be invoked manually.
    </p>
   </p></blockquote>
  </div>

 </div>

 
 






 






 






 






 






 







<h2>Table of Contents</h2><ul class="chunklist chunklist_reference"><li><a href="sessionhandler.close.html">SessionHandler::close</a> — Close the session</li><li><a href="sessionhandler.destroy.html">SessionHandler::destroy</a> — Destroy a session</li><li><a href="sessionhandler.gc.html">SessionHandler::gc</a> — Cleanup old sessions</li><li><a href="sessionhandler.open.html">SessionHandler::open</a> — Initialize session</li><li><a href="sessionhandler.read.html">SessionHandler::read</a> — Read session data</li><li><a href="sessionhandler.write.html">SessionHandler::write</a> — Write session data</li></ul>
</div>
<hr /><div class="manualnavbar" style="text-align: center;">
 <div class="prev" style="text-align: left; float: left;"><a href="function.session-write-close.html">session_write_close</a></div>
 <div class="next" style="text-align: right; float: right;"><a href="sessionhandler.close.html">SessionHandler::close</a></div>
 <div class="up"><a href="book.session.html">Sessions</a></div>
 <div class="home"><a href="index.html">PHP Manual</a></div>
</div></body></html>
